Add comprehensive rustdoc documentation to oracles module - #902

closed #834

Description

Comprehensive rustdoc documentation pass on the oracles module (contracts/predictify-hybrid/src/oracles.rs) as part of the GrantFox FWC26 campaign.

This PR adds production-grade NatSpec-style documentation covering:

• Module-level overview with architecture diagrams
• Complete trait and function documentation with error codes
• Security features and best practices
• Usage examples for common scenarios
• Oracle provider status and validation mechanisms

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Code refactoring
• Test updates

Changes Made

Documentation Enhancements (~280 lines)

1. Module-Level Documentation (~150 lines)

   • Comprehensive overview of oracle management system
   • Architecture diagram showing component relationships
   • Multiple usage examples (basic usage, whitelist management)
   • Security features documentation
   • Best practices for production deployments

2. Enhanced Function Documentation (~100 lines)

   • OracleInterface trait methods with complete error documentation
   • Safety notes for external contract calls
   • Implementation notes explaining design decisions
   • Best practices for health checking and error handling

3. Test Code Fixes (~30 lines)

   • Fixed 11 test cases missing GlobalOracleValidationConfig fields
   • Added max_deviation_z_multiple: None field
   • Added history_size: None field
   • Fixed test_oracle_validation_admin_config_auth initialization

Key Documentation Areas

• Security System: Whitelist-based access control, signature verification, replay protection, rate limiting
• Oracle Providers: Reflector (production-ready), Pyth (future support), Band Protocol (alternative)
• Validation Mechanisms: Staleness checks, confidence intervals, deviation guards, rolling median outlier detection
• Best Practices: 5 key recommendations for production use